
===========================================================================
  INTRODUCTION
===========================================================================

Available commands:

 PLAYSET.volume,tempo,beats,start,end  (settings)
 PLAY.voice,start?,string$  (song entry and playback)
 PLAYPAUSE.yes? (1 equals pause, 0 for resume)
 PLAYCLR (clears out a previous song from memory)
 PLAYSTOP (like PLAYPAUSE, but volume dropped)

This document is intended to explain how to use the user-defined PLAY 
command (and the other commands included with the package).  I felt that it
was better to go this route instead of integrating the instructions into 
the code itself (due to how bulky it would have ended up).  

I designed this command to be similar to the one provided by the Commodore 
128's BASIC interpreter, though I have never actually programmed in C-128 
BASIC.  The most important command in this package is the PLAY command, but
there are a few more commands included to help control the playback of the 
music that you create.

You will typically build a song in pieces using the codes/instructions 
outlined below.  The PLAY command itself converts your codes into a format 
that the music playing routine can more quickly interpret.  An area of 
memory is set aside to store the converted codes.  You must pick an area of
memory that won't come in conflict with other areas of memory that your 
program might employ.  If your music ends up being stored under the Kernal 
ROM (a very safe place to store the music), you won't be able to put a 
bitmap screen there, for example.

You can only build – and play – one song at a time.  In order to play 
more than one tune, you will need to clear out any previous music and feed 
new codes and instructions into memory.  This process is generally not too 
time consuming and might only take a second or so.

The actual playing of music is done via interrupts.  The PLAY command taps 
into the keyboard scanning routine. If you need to employ any kind of 
raster interrupts in your programs that make use of this software, you will
need to figure out how to mesh your interrupts with the one that the PLAY 
command utilizes.  Raster interrupts often exit through the key scan 
routine at least one time per screen refresh, so you'll need to divert 
control over to the music playing routine instead of the key scan routine 
(and then make sure the music routine exits to the key scan routine).  This
document doesn't go into details about how to properly do this (because I 
don't think there is a "one-size-fits-all" solution).

The software includes two different sets of frequencies for music notes.  
One set is for PAL computers, and the other is for NTSC computers.  You can
eliminate either set if you only wish to program for a specific audience 
(those with NTSC, or those with PAL).  I was never aware of the need for 
two sets of frequencies, but it's apparently a thing, so I incorporated the
two sets.

Four versions of the PLAY package are included on disk.  One version stores
song data beneath the Kernal, and another version stores song data in the 
area that runs from 49152 to 53247.  And then each of those versions have a 
version that displays "key strokes" to the screen (and the screen is moved 
to location 52224 because sprites are used).  The key strokes are there to 
help with "debugging" a song as you build and test it.  I suggest crafting 
a song this way before programming anything else – to make sure your songs
are doing right!  You can then delete lines 59993 to 63300, and then
"merge" a version of the package back onto the end that doesn't include the
"dancing" key stroke sprites.

__VERSIONS ON DISK_________________________________________________________

"PLAY CMD"      Storage at 49152 to 53247
"PLAY CMD+"     Storage at 49152 to 53247, plus sprite keystrokes
"PLAY CMD KR"   Storage under the Kernal (57344+)
"PLAY CMD KR+"  Storage under the Kernal (57344+), plus sprite keystrokes

The yellow sprite "bar" follows along with voice 1, the light green bar 
follows voice 2, and the light blue bar follows voice 3.  When rests are 
encountered, the sprites will appear static on the right side of the 
screen.  Multiple resting sprites will overlap.  What you want to look for
in the debugging process is for moments when the notes are not "hitting" at
the same time (if they are supposed to hit together).  For me, this was an 
especially important tool for making sure that the lower notes were in sync
with the top note.

Each version adds about 3K of compiled code to your programs (to their 
length once compiled).  The versions that display sprites also add another 
4K in the form of the extended command support library (for sound and 
graphics).  I designed the routines to not actually use any of Vision 
BASIC's sound commands in case you wish to keep your programs "LITE" (which
helps to keep your programs 4K smaller in size).

Since the text screen at location 52224 is used for the "key stroke" 
versions, the "PLAY CMD+" version can actually only store music up to 
location 52159 (a sprite shape is stored at location 52160 as well).  There
is a command available to adjust memory settings so that you can open up 
more memory for storage if needed.  When you are done using the "PLAY CMD+"
version (for testing), you can delete the user-defined command code and 
"merge" version "PLAY CMD" to the end of your program instead.  This will 
open things back up to location 53247.

The versions that store data beneath the Kernal have to briefly turn the 
Kernal off in order to access the stored data.  Interrupts are turned off 
at this time to prevent a crash.  I also added some code that is supposed 
to "prevent" NMI interrupts (like when you press the "RESTORE" key), but I 
did experience a crash a time or two when I pressed the RESTORE key TONS of
times while the music playing routine was running (my version of a "test"),
so I'm not entirely sure how much protection my "protection" offers.  If 
anyone knows of a way to improve the protection in place, let me know.

===========================================================================
  COMMAND:  PLAY.voice,play?,"codes"
===========================================================================

The PLAY command is used to store your music to memory in a format that the 
music playing routine can more quickly interpret.  Below are the codes and
instructions available, and beneath those are more extensive explanations
on how they work.

__CODES____________________________________________________________________

 C,D,E,F,G,A,B - Notes

        + or # - Sharp 
        - or $ - Flat

        W or 1 - Whole note 
        H or 2 - Half note 
        Q or 4 - Quarter note (unnecessary)
        I or 8 - Eighth note 
        S or 16- Sixteenth note

        *value - Duration in 16th notes, alternative to above durations
                (value can be 1 to 240, which is fifteen full measures)
        !value - Duration in jiffies (ranging from 1 to 65535)

             . - Dotted note

             R - Rest, followed by durations above
             M - A rest that waits to the end of the current measure

             O - Octave (followed by value 1 to 8)
             > - Octave increase by 1
             < - Octave decrease by 1

             V - Volume, followed by a value from 0 to 15, or...
                 V+ to increase volume by 1
                 V- to decrease volume by 1
                 V/ to half the volume
                 V* to double the volume
             N - Instrument, followed by a number from 1 to 16
             T - Tempo, followed by a number from 1 to 64
                 (sets number of jiffies per 16th note)
             L - Loop back to start or position marker
                 followed by a value from 0 to 240, number of times to loop
                 (zero means to loop back endlessly) 
             P - Position marker (to loop back to)
             J - Jumps to start of music for continuous play

__VOICE____________________________________________________________________

First, you specify the "voice" that you wish to store music for – choose 
voice 1, 2 or 3.  You can build your song one voice at a time, or you can 
build with any number of notes and hop around from voice to voice as you 
wish.  You'll need to keep track of things, though, because notes are added
in precise order for each voice.  You'll have to make sure that everything
synchronizes when all is said and done.  You could add ten quarter notes to 
voice 1, five half notes to voice 2, and four eighth notes plus a half note
plus six quarter notes for voice 3, and they should all reach the same 
point in a measure at the same time after playing all of those notes (as an
example).  Anyhow, for each use of the PLAY command, you can only work with
one voice at a time.

__PLAY?____________________________________________________________________

Second, you specify whether you want the music to start playing.  The music
won't play until the notes that follow this parameter have been fed into 
storage.  Generally, the value for this parameter should be zero until you
have fed your entire music score into memory (otherwise, strange results
could happen).  When you are ready to play your song, you will specify how
many voices you wish to play (1, 2 or 3), and the music will only play for
the number of voices you choose – even if you only specify one or two
voices and yet music has been fed into memory for all three voices.  You
don't have to enter music for all three voices – you can save one or two
voices for sound effects in a game, for example.  The RND command uses 
voice 3 output to help generate random numbers (if you have it set up for
that), so you probably won't want to play notes in voice 3 (in that 
circumstance).

So if you want to play just a single voice, enter a value of "1" for this 
parameter and the music will start playing for the voice indicated at the 
beginning of the PLAY command.  If you want to play all three voices, enter
a value of "3" instead.  And if you only want to play two voices, it gets 
a tiny bit complicated.  In this case, the voice at the start of the PLAY 
command will be chosen, but also the next voice in order.  If the voice 
parameter is "1", then voices 1 and 2 will start playing.  If the voice 
parameter is "2", then voices 2 and 3 will start playing.  And if the voice
parameter is "3", then voices 3 and 1 will start playing (it wraps back 
around to 1).  Remember, only select to play music once you have entered 
your entire score into memory.

If you have entered your entire song into memory, you can elect to issue
a PLAY command with no third parameter – for the mere purpose of starting
the play process.

__"CODES"__________________________________________________________________

Finally, you get to enter a string of codes.  These codes contain your 
notes and instructions to the player.  Before you start entering any notes,
you may wish to tell the player which instrument you want to use for the 
voice in question.  Each voice can have its own instrument, and you may 
need to specify an instrument for each voice if you don't want "piano" 
chosen for each voice, which is the default.  You can also change 
instruments at any point for any voice, if you wish.  Also, at this point,
you may want to set up a "point" for the music to jump back to for 
repetitious play.  You may also wish to specify the octave for the notes 
that follow (the default is 4), and you might also wish to set the volume
(you can set the volume for any voice, but it will affect ALL voices, so 
you only need to set it one time for one voice, and the default is a value
of 15).  

Because the third parameter for the PLAY command is a string, you can 
substitute a string variable if you wish.  This allows you to build strings
of codes and instructions, combining various elements together.  You can 
use the same string multiple times, but change a value within the string 
before each use for example.  

Now let's talk about entering notes...

__NOTES____________________________________________________________________

The notes you enter will play in the current octave for the current voice. 
Octaves start at a C note and end with a B note (think "piano").  If your 
first note is a C, and you go down to a B note, you'll have to change the 
octave, for example (I'll explain how to do that soon).  Anyhow, just type
the note you wish to play – C, D, E, F, G, A or B.  If the note needs to
be sharp or flat, you'll have to indicate this next.  Use "#" or "+" for 
sharp notes, and "$" or "-" for flat notes.  You can also double up on 
these if needed – like "##" to sharpen twice.

__DURATION_________________________________________________________________

Next comes duration!  If the note is a quarter note, you don't need to add
anything!  But for other durations, you'll need to add a letter or a 
number.  Use "W" for whole note, "H" for half note, "Q" for quarter note 
(unnecessary), "I" for eighth note (sorry, but E can't be used – duh!), 
and "S" for sixteenth note.  I personally don't like using the letters, so
I added numbers to the mix as an alternative.  With numbers, just think 
"denominator".  So "1" is for a whole note, "2" is for a half note (as in 
1/2 <- denominator of two), "4" is for a quarter note (also unnecessary), 
"8 is for an eighth note, and "16" is for a sixteenth note!  I personally 
find this system much easier to interpret visually.

Okay, so for dotted notes, simply add a period – after the duration, of 
course!

__UNUSUAL_DURATIONS________________________________________________________

Sometimes you'll see notes that are joined together (in musical notation) 
to create strange durations – maybe you'll see a half note plus a 
sixteenth note joined together.  Well, that's what the asterisk is for!  
Type an asterisk and follow it by a duration expressed as the number of 
sixteenth-notes you wish to play.  So in this example of a half note plus a
sixteenth note, you'll type "*9" – because a half note is 8 sixteenth 
notes, and you need to add one more sixteenth note to the mix (for a grand 
total of "9").  Anyhow, use this notation in place of the note values 
described in the previous paragraphs).  There is no symbol you can use to 
join notes together with, so this is the solution in place.

And if you need something a bit more specific, you can also specify the 
number of "jiffies" to play a note for.  Just type an exclamation point 
followed by the number of jiffies you need the note to play for (a "jiffy"
is 1/60th of a second).  In the process of creating this software, I 
learned that PAL systems also count 60 jiffies per second, even though the
screen refresh rate is 50 frames per second.  So you should be okay writing
music for either system – PAL or NTSC (if you use rater interrupts in 
conjunction with the PLAY command software, you may not be able to specify
jiffies and expect things to play the same on both systems).

I tried to come up with a way to incorporate "slurs" into the mix, but I 
wasn't getting the results I was expecting.  For cases like this, you might
need to set up a separate instrument that doesn't "attack" so hard, and 
switch to that instrument for slurs.

__RESTS____________________________________________________________________

What about rests?  Glad you asked!  Simply use "R" instead of a note, and 
follow it with the same timing codes that you would use for musical notes.
So, "RH" would be a "half rest", for example.  The PLAY command treats 
rests as if they were notes, but a note is simply not played.  You also 
have a special type of rest at your disposal – a rest that plays out for 
the remainder of the measure.  This helps to simplify things for you.  So 
if you play a quarter note at the start of a measure and want to follow it
up with a "rest", you can simply type "M" (for "measure") after the music
note.  For example, "CM" will play a "C" note and the remainder of the 
measure will remain quiet for the voice in question. 

__OCTAVES__________________________________________________________________

Okay, so let's move on to the rest of the "controls" at your disposal!  To
change the current octave for a voice, you simply type "O" and follow it 
with a value from 1 to 8.  The PLAY command for the C128 uses values 0 to 
7, I think, but I don't like starting things off at zero, so I chose values
1 to 8 instead.  Middle "C" starts in octave "4".  I've provided a 
reference image (with colored notes and such) that should help you to 
figure out which octave value you need to use when playing certain notes. 
You can also use the "<" symbol to lower the octave by one, or use the ">"
to raise the octave by one.  You can use multiple symbols for lowering and
raising the octave (as needed).  Errors will result if you go out of bounds
(your program will halt).  If you change the octave for one voice, it will 
not affect what happens in the other voices at all.

__INSTRUMENTS______________________________________________________________

If you wish to change the instrument, just use "N" followed by a value from
1 to 16 ("I" has been taken, so now it's "N" for "iNstrument").  I copied 
the instruments from the C128 version of the PLAY command, but I chose to 
also shift the values here.  So the "piano" instrument starts at "1" for my
version of the PLAY command instead of zero.  I added one bonus instrument 
to the mix (number eleven) and it's similar to the piano, but you can add 
more instruments if you'd like (in the source code), or you can even change
the existing ones that are there to whatever you'd like.  You can change 
the instrument at any point in your song, and you'll want to change the 
instrument for each voice (starting out) if you don't want to go with the 
default of "piano".

 #  INSTRUMENT   A  D   S  R  WF PW
 1  Piano        0  9   0  0  4  1536 (high nybble = 6)
 2  Accordion    C  0   C  0  2                            C=12
 3  Calliope     0  0   F  0  1                            F=15
 4  Drum         0  5   5  0  8
 5  Flute        9  4   4  0  1
 6  Guitar       0  9   2  1  2
 7  Harpsichord  0  9   0  0  4  512  (high nybble = 2)
 8  Organ        0  9   9  0  4  2048 (high nybble = 8)
 9  Trumpet      8  9   4  1  4  512  (high nybble = 2)
10  Xylophone    0  9   0  0  1
11  Piano 2      1  9   0  0  6  1536 (high nybble = 6)

Wave Form (WF):

  1 = triangle, 2 = sawtooth, 4 = pulse  and  8 = noise

__VOLUME___________________________________________________________________

If you want to change the volume, just type "V" and follow it with a value 
from 0 to 15.  In this case, I did keep zero in the mix because it turns 
the volume off completely.  And again, you'll be affecting the volume for 
ALL voices!  I did add some codes to allow for more dynamic volume 
controls.  For example, let's say that you want to fade the same section of
music to zero as it repeats.  You can use "V+" to increase the volume by 1 
point, you can use "V-" to decrease the volume by 1 point, you can use "V/"
to divide the volume in half, and you can use "V*" to double the volume.  
If you increase the volume past 15, it will cycle back to zero, and if you 
decrease the volume below zero, it will cycle back to 15.  So you'll need 
to count things out properly.  Also, if your volume is 15 and you "half" 
it, it will become "7" because a bit will be lost in the process.  And if 
you half it again, it will become "3", and if you half it again, it will 
become "1" (and from "1" it will be halved to zero).  Doubling is pretty 
much straightforward.  You can double from 1 to 2, and from 2 to 4, and 
from 4 to 8, but doubling a value of "8" will push the bit to "16", which 
is the same as zero.  You can also adjust the volume between each and every
note, but again, all voices will be affected.

__TEMPO____________________________________________________________________

What about the tempo?  Well, you can adjust the tempo any time you want, 
but it will affect ALL voices.  So you'll want to feed the notes for all 
voices into memory up to the measure that you want to adjust the tempo for.
And for the parts of your song that repeat, you can't alter the tempo for 
notes that are already stored to memory (durations are stored to memory as 
"jiffies", so they're "set").  In other words, if you speed up the tempo 
and jump back to replay a section of notes, those notes won't play any 
faster.  To change the tempo, you type "T" and follow it with a value from 
1 to 64.  The "tempo" value sets the number of jiffies for a sixteenth 
note.  The default is 6, so a sixteenth note lasts 1/10th of a second by 
default.

__LOOPING__________________________________________________________________

If you want to have a part of a song repeat, you place a "P" in the spot 
where you want the music to jump back to ("P" is for "Position"), and then 
you issue a "loop" instruction.  To loop back to the chosen position, type 
"L" and then a value indicating the number of times you wish to loop back.
So "L4" will play your selection a total of four times.  To have things 
repeat endlessly, type "L0".  You can have multiple sections of a song 
repeat, but you cannot have "nested" loops.  Now, if you want to loop back
to the start of your song, you don't need to place a "P" at the beginning 
-- since loops will loop back to the start by default.

You will need to use "P" and "L" for each voice, typically.  You might have
a measure or more in the bass, for example, that might repeat several times
while the top voice or two are meandering from measure to measure.  In this
case, you can have that bottom measure or two repeat the number of times 
that are necessary – without the upper voice or two repeating in any 
fashion.

If you have some music for a game that you want to repeat over and over 
again, you can also use the "jump" instruction.  Use "J" to do this, and it
will cause your song to repeat over and over again from the start.  Unlike 
looping, you don't specify a position to jump back to.  Jumps always go 
back to the start of things.  One benefit with "jumping" is that it allows
for a type of "nested" looping.  You simply do your looping on the "inside"
of your song, and you issue a jump at the end so that the entire song plays
repeatedly.  If you have a loop ("L") that jumps back to the start, and 
then you also have a jump ("J") that also jumps back to the start, you 
might need to place a position marker ("P") at the start of the score.  The
"Minuet" example song has two loops, and it also repeats endlessly, but I 
discovered that I needed to place a "P" at the start (for each voice).  

__AN_EXAMPLE_______________________________________________________________

You can examine the "Minuet" song in the "PLAY DEMO" file on disk to see 
how all of the codes and instructions work together to form a song.  But 
here is a simpler example to look at first:

10 clr:cls
20 keypress
30 play.1,0,">bagabbb2aaa2b>dd2"
40 play.1,1,"<bagabbbbaabag1l2"
50 keypress

You should be able to add these lines to any version of the PLAY software.

In line 30, I raised the octave (from the default of "4") using the ">" 
symbol – because the notes didn't sound right to me in the default octave.
Then the notes "BAGABB" are all quarter notes.  A half note follows – 
"B2".  Next comes two more quarter notes, followed by another half note – 
"AAA2".  Then a quarter "B" note.  And then I raise the octave again for 
the two notes that follow – "DD2" (one quarter note, and one half note).

In line 40, I lowered the octave back to the previous level and proceed to 
play twelve quarter notes – "BAGABBBBAABA".  Then a whole note "G1".  And 
finally comes "L2" which causes the song to play twice in a row.  I didn't 
change the time signature to 4/4 timing, but I didn't need to because I 
didn't use an "M" code.  All of these notes are from memory because I used 
to play this song on "recorder" in elementary school.  I had to correct my 
teacher in that class because she had two "B" notes in the place of the "D"
notes (she made the changes).

It seems that the most common version of this song starts on an "E" note 
instead of "B" (C major instead of G major), but you'll still recognize the
tune.  I also saw a version where a couple of the notes have different 
durations:

30 play.1,0,">b4.a8gabbb2aaa2b>dd2"
40 play.1,1,"<b4.a8gabbbbaabag1l2"

===========================================================================
  COMMAND:  PLAYSET.volume,tempo,beats,start,end
===========================================================================

This command allows you to access some player settings.  If you want to 
make changes to these settings, make sure to do so before using the PLAY
command.

 volume - the volume for all three voices
  tempo - the tempo (the number of jiffies per 16th note, 1 to 64)
  beats - the number of beats per measure (typically 3 or 4)
  start - the starting address of music storage
    end - the ending address of music storage

The tempo and volume are accessible via the PLAY command, but here you can 
also set the beats per measure, and the place where music data gets stored 
for playback.  The default setting for "beats" is "3", but you can set it 
to "4" as well.  For signatures with 6/8 timing, just go with 3/4 timing.  
Beats are always going to be quarter notes unless you wish to go into the 
code and change it yourself.  Setting the beats per measure is really only 
needed if you are going to use the "M" code.  Otherwise, it's really
completely and utterly unnecessary to worry about it.

As for relocating the area for music storage, you can place it lower in 
memory, but you run a higher risk of running into program storage, variable
storage, and string storage.  The "Minuet" song uses only 526 bytes of 
storage, counting the buffer, so you will probably only need to increase 
the size of the storage area if you get an "overflow" error.  It might be 
in your best interest to actually decrease the size of storage when you 
find out how much storage is being used after all is said and done (to help
make room for other things).  You might wish to push the "start" up to a 
higher value, for example.  But you might also want to put some kind of 
graphics data in the area from 49152 to 53247, so moving the storage would 
make sense there.

I doubt that users will experience a problem with the buffer spilling past 
80 characters, but you can manually change the size of the buffer in lines 
60904 and 60916 of the code.  Just change the "80" to a higher value.

===========================================================================
  COMMAND:  PLAYPAUSE.yes?
===========================================================================

This command has a single parameter and allows you to "pause" the song that
is playing.  Set the parameter to "1" to pause your song, and set the 
parameter to "0" to resume playback.  The only thing the command actually
does is restore the key scan pointer to its default value during the pause.
If you have any notes playing that are paused during the "sustain" part of 
the cycle, you might want to temporarily reduce the volume during a pause.
Otherwise, you might find the constant tone(s) annoying.

===========================================================================
  COMMAND:  PLAYCLR
===========================================================================

If you want to play more than one song in your program, use the PLAYCLR
command to clear out the song storage.  Then you can proceed to funnel your
next song into the storage area using another set of PLAY commands.

===========================================================================
  COMMAND:  PLAYSTOP
===========================================================================

To stop a song from playing, use the PLAYSTOP command.  It pretty much 
works identically to the PLAYPAUSE command, but it doesn't require a 
parameter, and it shuts off the volume.  It doesn't attempt to "close" any 
gate bits, though.  The reason for this is because you might be using the 
output of voice 3 for random number generation, for example.  If you don't 
want the volume shut off, you can use the PLAYPAUSE command instead and 
manually clear out whatever sound registers you might need to clear out.  
For example, you might have sound effects being played in the "unused" 
voices and you might wish for them to keep playing.

===========================================================================
  EXTRA STUFF!
===========================================================================

Here is some extra information that you might find useful.

__TUPLETS__________________________________________________________________

If you want to play "triplets", you can use a duration of 3 or 6 – as long
as your tempo is divisible by 3 or 6 (for both values, respectively).
Below is an example on how it might look:

100 play.2,0,"<c2cccwj"
110 play.1,2,"c6e6g6<aaawj"
120 keypress:playstop

The "triplets" are in line 110, followed by two quarter notes and a whole
note.  The first three notes – C-E-G – will play out in the time it takes
to play two quarter notes.  Below is a variation that plays three notes in 
the span it takes to play a whole note:

100 play.2,0,"<cwcwj"
110 play.1,2,"c3e3g3<awj"
120 keypress:playstop

I'm pretty sure any form of "tuplets" can be played if your chosen tempo 
value is divisible by the denominator of the note's duration.  So a "C5" 
note should work if the tempo is "5" or "10".  And a "G7" note should work 
if the tempo is "7", for example.  I left the text for the examples above 
in lowercase so that it can be copied into the VICE emulator.

__MEMORY_USAGE_____________________________________________________________

And if you want to know how much memory your song is taking up in the song
storage area, you can supply a variable at the beginning of your final use
of the PLAY command (turning it into a user-defined "function").  It would
look something like this:

100 play.2,0,"<c2cccwj"
110 play.mem=1,2,"c6e6g6<aaawj"
120 keypress:playstop

If you were to print out the value of "MEM", you will discover that the
song takes up 108 bytes of memory (of which 80 belong to the buffer).  So
the song really only uses 28 bytes of memory.  Six of those bytes include
three termination bytes and three bytes that set each voice to "piano" as
the default instrument.

__KEY_SIGNATURES___________________________________________________________

Since there is no way to design a "key signature", you'll have to sharpen
or flatten all notes manually.  But you can go into the source code and
alter the "offsets" in line 60298.  By raising or lowering the appropriate
values here, you can effectively produce a kind of "key signature".  The
values in line 60298 correspond with the letters A through G.  For our 
example song "Minuet", we could accomplish "G major" by changing a single
value.  All "F" notes are "sharped" in G major, so we could change the "6"
in line 60298 to a "7" (this moves the "F" a half step higher).  Sharps
increase numbers by 1, and flats lower them by 1.

The default "time signature" is 3/4 timing.  If you wish to change it in 
the source code, you can set "BEAT" in line 60902 to 4 (instead of 3).

__PAL_AND_RASTER_INTERRUPTS________________________________________________

If you want to add raster interrupts to your program, I can't fully direct
you on how to graft it all together, but you might want one of your 
interrupts to exit into the song-playing routine at 61300.  Since PAL 
systems only refresh the screen fifty times a second, this might cause 
songs to play slower on PAL systems.  You may wish to remove the letters 
"REM" from line 60982 to allow for a timing adjustment.  For the sake of 
accuracy, you'll want your "tempo" to be divisible by six.

__EDITING_INSTRUMENTS______________________________________________________

If you want to add instruments or edit existing ones, you can alter the 
values in lines 61850 to 61880.  The values here are in hexadecimal (I 
don't like hex values, but they work better here).  "Attack" and "Decay" 
values are in line 61850.  The first digit of each hex value is the attack
value, and the second digit is the decay value (both range from 0 to 15, 
but in "hex").  The "Sustain" and "Release" values are in line 61860.  The
first digit of each hex value is the sustain value, and the second digit 
is the release value (both range from 0 to 15).  The waveform values are 
in line 61870.  Only the first digit matters (range 0 to 15).  And the 
"pulse" values are in line 61880.  Only the second digit matters and it 
sets the "high nybble" of the pulse "width" (range 0 to 15).

Each value on each line is in instrument order, so the first value on each 
line only pertains to the "piano" instrument, for example.  You'll have to 
count out from the start of each line to access other instrument settings. 
When it comes to hexadecimal digits, digit values 0 to 9 are the same as 
they are for decimal values (in other words, "9" equals "9").  To represent
values of 10 to 15, use "A" for 10, "B" for 11, "C" for 12, "D" for 13, "E"
for 14, and "F" for 15.

===========================================================================
  THAT'S ALL FOLKS!
===========================================================================

I might modify the code if I have time – to improve it, of course.  There 
might be bugs in the code and/or there might be errors in this "manual", so
please let me know if you find anything!  The player I've created isn't 
intended to match the quality you'll find in SID music – I don't have the 
expertise to pull off a lot of the fancier stuff you'll find in SID 
players.

